.. _example-predominance-phreeqc-01:

01 - C-Fe System
================

Iron speciation against pH and dissolved carbon, computed twice from the same
input with two different thermodynamic databases. The chemistry does not
change between the two runs. The diagram does.

This is the question of the Database examples asked from the other end:
those compare what databases contain and what constants they give, this one
shows what the difference does to a result you would publish.


The input
---------

.. raw:: html
   :file: phreeqc_dat.html

A dilute ferric solution -- 0.1 µmol/l Fe at pe 8.45, 25 °C -- with chloride
balancing the charge. Two parameters are swept: pH from 4 to 12, and total
dissolved carbon, written as ``@{$10^C_param$}@`` so that the parameter is
the exponent and the axis is logarithmic by construction, from 10⁻⁶ to
10⁻² mol/kgw.

Everything above is held fixed across both runs. The *only* difference
between the two studies is which database they target.


The same input, two databases
-----------------------------

.. figure:: C_minus_FeSpecies_op_phreeqc_dat_cp_.svg
   :alt: Iron predominance diagram computed with phreeqc.dat, four regions
   :align: center

   With ``phreeqc.dat``: four regions. Fe+2 in the acid corner, then the
   ferric hydrolysis series Fe(OH)2+, Fe(OH)3 and Fe(OH)4- as pH rises. The
   carbon axis does almost nothing -- the boundaries are near-vertical,
   because nothing in this database lets carbonate compete for the iron.

.. figure:: C_minus_FeSpecies_op_sit_dat_cp_.svg
   :alt: The same calculation with sit.dat, with an additional Fe(OH)CO3 region
   :align: center

   With ``sit.dat``: five regions. Everything above, plus **Fe(OH)CO3**,
   which takes a field of its own at high carbon -- and the carbon axis
   suddenly matters, because there is now a species that responds to it.

``sit.dat`` contains an iron-carbonate complex and ``phreeqc.dat`` does not.
That one absent species is the whole difference, and the consequence is not
subtle: the two diagrams support different conclusions about whether
carbonate controls iron speciation in this system.

The first database does not report an uncertainty or warn that something is
missing. It answers the question it was asked, using what it has. Checking
what a database contains before trusting a result is not a formality, and
the first Database example is the tool for it.


Styling the diagram
-------------------

.. figure:: C_minus_FeSpecies_op_whiteformat_cp_.svg
   :alt: The sit.dat diagram redrawn with plain outlines and no fill
   :align: center

   The ``sit.dat`` diagram again, with the predominance area settings
   overridden: no fill, plain boundaries, labels only. The same data drawn
   for a different medium -- this is the version that survives being printed
   in black and white, or being dropped into a figure that already uses
   colour for something else.

   The override is on the trace, so the colouring is a property of the plot
   rather than of the study. Duplicating a plot and restyling the copy costs
   nothing, because neither copy re-runs the model.


Try it
------

* Point both studies at ``llnl.dat`` or ``minteq.v4.dat`` and see how many
  diagrams this system has.
* Narrow the carbon range to where Fe(OH)CO3 appears and re-run, to see the
  boundary properly.
* Change pe and watch the Fe+2 field grow or shrink.


Source
------

* Parkhurst, D. L. and Appelo, C. A. J. (2013). *Description of input and
  examples for PHREEQC version 3.* U.S. Geological Survey Techniques and
  Methods, book 6, chapter A43. Both ``phreeqc.dat`` and ``sit.dat`` are
  distributed with PHREEQC and carry their own sources in their headers.